What

Follow-up to #1072 addressing the structural issues that let the missing-processExitError bug class exist, in one pass:

1. requireExecSuccess combinator (+ ~30 site conversions)

requireExecSuccess(result, message, extra?) in src/utils/exec.ts guards an allowFailure result and throws the curated COMMAND_FAILED (flag set via execFailureDetails) itself. Pure guard-and-throw sites collapse from five lines to one expression, and forgetting the flag becomes impossible.

Design note: this is deliberately a result-side combinator, not an ExecOptions.failure knob. Tool providers, adb providers, and CommandExecutorOverride are SDK-supplied callbacks that return results without throwing — an option interpreted at spawn time would silently not fire on those paths. The combinator behaves identically under every executor. extra accepts a function so failure-only work (hint classification) is not paid on success.

Sites with tolerance branches ('found nothing to terminate', isMissingAppErrorOutput, 'already booted'), pre-throw cleanup, or exit-0 reachability keep their explicit shape.

2. Self-enforcing guard

src/__tests__/exec-wrap-guard.test.ts scans src/ and fails when an AppError('COMMAND_FAILED', ...) details literal rebuilds the stdout/stderr/exitCode trio inline (longhand or shorthand) without the helper. Intentional holdouts opt out with // exec-guard-allow: <reason> — every marker documents why that site stays unflagged. The guard immediately proved its worth by finding three wrap sites the July audit missed (daemon/runtime-hints.ts run-as probe, daemon/device-ready.ts not_ready branch, perf.ts export table) — all converted here.

3. Provider-boundary result coercion

coerceExecResult normalizes stdout/stderr to strings (and non-number exitCode to 1 — the same failure branch such a result already landed in at every guard) once at the three boundaries where SDK-supplied callbacks hand results back: executor overrides in runCmd/runCmdStreaming, the apple tool-provider scope, and the android adb-provider scope. The per-site String(result.stdout ?? '') defensiveness in devicectl/simulator/device-ready/target-shutdown/plist is removed — downstream code can now trust the types.

4. Kernel: stderr-excerpt noise stripping + documented details contract

• firstStderrLine strips adb:/xcrun:/simctl:/error: prefixes before rendering, so agents read device offline instead of adb: error: device offline. The skip/strip lists stay in the kernel deliberately (platforms cannot hook normalizeError); a comment marks the registry escape hatch if the lists grow.
• AppErrorDetails is now exported and documented — the magic keys (hint, processExitError, retriable, reason, diagnosticId, logPath, stdout/stderr/exitCode) carry types and doc comments. exitCode admits null to mirror raw child-process exit events (signal kills).

5. devicectl wrap dedupe

runIosDevicectl gains tolerateOutput; the devicectl uninstall path in app-install.ts reuses it instead of duplicating the whole wrap + hint resolution. Small behavior note: its failure hint now falls back to the devicectl default hint instead of no hint.

Behavior changes a reviewer should know

• One test expectation updated: an Android perf failure reason is now device offline (prefix stripped) instead of error: device offline.
• Converted requireExecSuccess/execFailureDetails sites that previously omitted stdout/exitCode from details now include them.
• Provider results with non-string output no longer leak undefined into details/messages; non-number exitCodes coerce to 1 (previously they already fell into every failure branch, but with undefined in details).

Testing

• pnpm check:quick clean, pnpm format applied.
• Full unit suite: 330 files, 3104 tests pass (one daemon-client abort test is flaky under suite-wide contention only; passes in isolation — known issue).
• New unit tests: requireExecSuccess success/failure/lazy-extras, coerceExecResult identity + repair, three stderr noise-prefix cases in errors.test.ts.

Relates to ADR 0010 (#1071) section 4 — this PR strengthens "prefer exec.ts errors as-is" by making the curated-message case expressible without hand-rolling.